# SParser

> Самостоятельный парсер, генератор сообщений и чат-боты для школьного расписания уроков.

![](docs/_images/telegram.png)

 <!-- some shields -->
<p align="center">
  <a href='https://sparser.readthedocs.io/ru/latest/?badge=latest'>
    <img alt="Documentation", src='https://readthedocs.org/projects/sparser/badge/?version=latest'>
  </a>
  <img alt="Version" src="https://img.shields.io/badge/dynamic/toml?url=https%3A%2F%2Fnotabug.org%2Fmilinuri%2Fsparser%2Fraw%2Fmaster%2Fpyproject.toml&query=tool.poetry.version&prefix=v&label=SParser&color=green">
  <img alt="License" src="https://img.shields.io/badge/dynamic/toml?url=https%3A%2F%2Fnotabug.org%2Fmilinuri%2Fsparser%2Fraw%2Fmaster%2Fpyproject.toml&query=tool.poetry.license&label=License&color=red">
  <img alt="Python verion" src="https://img.shields.io/badge/dynamic/toml?url=https%3A%2F%2Fnotabug.org%2Fmilinuri%2Fsparser%2Fraw%2Fmaster%2Fpyproject.toml&query=tool.poetry.dependencies.python&label=Python">
</p>


Приветствую в проекте.
Когда-то мне надоело смотреть расписание в гугл таблицах.
Оно просто долго открывалось, тормизили или не открывались вовсе.
Потому было принято решение написать дополнение к этому расписанию.

**И того мы получаем**:

- Автономный парсер расписания уроков.
- Возможность **быстро и удобно** просматривать расписание.
- Инструменты для работы с расписанием.
- Telegram и vk чат-боты.
- Отслеживание изменений в расписании.
- Автоматические оповещения.
- И многое другое...

Проект развивается и постепенно добалвяются новые функции.
Почитать о всех возможностях вы можеет в
[документации](https://sparser.readthedocs.io/ru/latest).


## Установка

Скопируйте репозиторий проекта:
```bash
git clone https://notabug.org/milinuri/sparser
cd sparser
```

Установате зависимости через [poetry](https://python-poetry.org/):
```bash
# Только парсер и генератор сообщений
poetry install

# Если мы захотим запустить своего telegram бота
poetry install --with telegram
```

> Установка **Вк бота** закончится ошибкой из-за неразрешённых зависимостей.

Или через pip + Python venv:
```bash
# Создаём и активируем виртуальное окружение
# Запускать проект нужно тоже из виртуального окрежения
python -m venv venv
source venv/bin/activate

# Устанавливаем ВСЕ зависимости
pip install -r requirements.txt
```


## Запуск

На примере Telegran бота. (`v2.0 (sp v5.7)`).
Перед первым запуском скопируйте файл `.env.dist` в `.env`.
В файле `.env` укажите ваш Telegram токен бота.

```sh
# .env
...
TELEGRAM_TOKEN="YOUR_TELEGRAM_TOKEN_HERE
...
```

После указания токена вы можете запускать бота...

Через Poetry:
```
poetry run python telegram.py
```

Через Python venv.
```sh
source venv/bin/activate
python telegram.py
```

Запуск Вк бота происходит по похожему принципу.
Запишите в `.env` ваш токен от группы ВК.

```sh
# .env
...
VK_TOKEN="Ваш Вк токен Туть"
...
```

И после запускаете через *Python Venv*:
```sh
source venv/bin/activate
python -m sp_vk
```


## Чат-боты

### Telegram

Первую версию написал Артём Березин ([@optemikk](https://t.me/optemikk)), положив начало проекту.

Взаимодействие с ботом проиходит через запросы или клавиатуру.

В **текстовых запросах** вы указываете что вам нужно получить.
Будь то расписание для класса, урока или кабинета.
Вы можете уточнить свои запросы днём, классом, кабинетом, уроком.
Порядрок аргуметов в запроссе не важен, развлекайтесь.

**Клавиатура бота** позволяет дотянутся до всех основных разделов.
Вам не нужно писать однотипные запросы или вводить каждый раз команды.

Также для доступа к осноным разделам вы можете использовать команды.

**Функции бота**:

- Использование inline-клавиатуры.
- Использование текстовых запросов для получения расписания и поиска.
- Постраничное обучение написанию запросов (`/tutorial`).

- Управление классом по умолчанию (`/set_class`).
  - `->` Преимущества указанного класса (`/cl_features`).
  - `->` Не привязывать пользователя к классу (`/pass`).

- Домашнее сообщение (`/help`, `/start`).
  - Шпаргалка по написанию запросов.
  - `->` Дополниельная клавиатура (`/info`).
  - `->` Настройка уведомлений (`/notify`).
  - `->` Расписание на сегодня/завтра (`/sc`).

- Сообщение статуса (`/info`).
  - Статус `sp`.
  - Авторы и версия бота.
  - Время последнего автоматического обнолвения.
- Дополнительная клавиатура.
  - `->` Смена класса пользователя (`/set_class`).
  - `->` Просмотр списка изменений (`/updates`).
  - `->` Просмтр счётчиков расписания (`/counter`).
  - `->` Динамическая справка о написании запросов (`/tutorial`).
  - `->` Намерения пользвоателя (`/intents`).
- Просмотр списка изменений (`/updates`).
  - Клавиатура перемещения по страницам.
  - Переключение режима просмотра с общего на "для класса".
  - Клавиатура выбора намерения.
- Просмотр счётчиков расписания (`/counters`).
  - Переключение группы и режима просмотра.
  - Клавиатура выбора намерения.
- Настройка уведомлений бота (`/notify`).
  - Полное отключение уведомлений.
  - Сброс уведмолений.
  - Включение/отключение рассылки в указанный час.
- Расписание на сегодня/завтра (`/sc`).
  - Переключить просмотра с сегодня/завтра на неделю.
  - Выбор дня неделю для расписания.

- Намерения пользователя (`/intents`).
  - `->` Добавить новое намерение (`/add_intent`).
  - `->` Изменить намерение.
  - `->` Режим удаления намерений (`/remove_intents`).

- Добавить новое намерение (`/add_intent`):
  - Укажите имя намерения.
  - Укажите параметры намерения.

- Изменение намерения:
  - Изменить параметры намерения.
  - Удалить намерение.

- Режим удаления намерений (`/remove_intents`):
  - Удалить намерение по нажатию на его имя.
  - Удалить все намерения.


**Доступные счётчики**:

| counter  | target                  |
| -------- | ----------------------- |
| cl       | days, lessons. cabinets |
| days     | cl, lessons. cabinets   |
| lessons  | cl, days, main          |
| cabinets | cl, days, main          |


### vk (sp v5.7)

![](docs/_images/vk.png)

Разделы на фото:

- Смена класса (`/set_class`).
- Главное меню (справка).
- Результат запроса к расписанию.
- Информация о боте и парсере.

Копирует функции Telegram версии бота.
Иногда некоторые функции урезаются, некоторые напротив расшираются.
Из-за особенности платформы.

Вы так же можете использовать **текстовые запросы**.
**Клавиатура бота** в отличие от Telegram бота не прибита к сообщению,
а находится отдельно.
Это позоляет управлять всем ботов целиком, а не привзяываться к
отдельному сообщению.

Обновляется чуть реже, чем Telegram версия бота.
Если вам нужно обновление, то напишите об этом в
[Чат Telegram](https://t.me/+cXUXXlLgcJMzMzli)

[Статья о боте в Вк](https://vk.com/@chiorin-kak-poluchit-raspisanie).
Написана для более старой версии бота и может быть места устаревшей.

### Некоторые ограничения чат-ботов

Не смотря на почти полную поддержку генератора сообщений, существуют
некоторые ограничения, связанные с чатами.

**Настройка намерений**:
Пока нет возможности полноценно представить намерения через клавиатуру.
Это отражается на списке изменений и счётчиках.
Однако это не столь критично для большинства пользователей ботов.

> Примечание: Частично решена в Telegram бота, добавлением редактора
> намерений с версии v2.2.

**Ограничение длинны сообещний**.
Приходится соблюдать баланс между информативностью и читаемостью.
Порой это не всегда получается.
Это сказывается на удобсте использования и интуитивности бота.
Модет быть решена предварительным написанием справки об использовании.


## Консоль

![](dosc/_images/spm_console.png)

Простая обёртка для работы с генератором сообщений.
Имеет достаточно простой интерфейс.
Не требует установки дополнительных зависимостей.
Использует все основные методы генератора сообщений.
Будет полезен для отладки работы парсера и генератора сообщений.
А также как пример кода для написания ваших собственных обёрток.

Вот пример некоторых команд:
```bash
# Получить справку по командам
python spcli.py --help

# Установка класс по умолчнию
python spcli.py --set-class 8а

# Быстрое получение расписания (если указан класс)
python spcli.py
```


## Поддержка

Проект распространяется под свободной лицензией.
А значит вы можете свободно использовать весь инструментарий
в своих целях.

Мы будем очерь рады, если вы внесёте свой вклад в развитие этого
проекта.